\vssub
\subsection{~Distribution}\label{sec:install}
\vssub

\noindent Through version 5.16, \ws\ public releases were released as tarballs. 
After the public release of version 6.07, \ws\ will move to an open development 
paradigm and source code is distributed via Github. 

\vssub
\subsection{~Installing}
\vssub

To clone the source code
\command{ git clone https://github.com/NOAA-EMC/WW3 }
Public releases can be accessed by checking out tags: 
\command{ git checkout VERTAG }
where VERTAG is the public release tag, for example v6.07. 

\vssub
\subsection{~Setting up}
\vssub

After cloning the \ws\ repo, there are two steps to follow.  The first step 
is to run the script {\file model/bin/w3\_setup} which will compile auxiliary 
programs and setup the environment file {\file wwatch3.env}, which will be 
stored locally in the bin directory. This file sets options for default C 
and FORTRAN compilers which will only be used by the preprocessor. Except 
in specific cases, this default setting can be used as is. Running the 
script alone will give full usage, or to execute also supply the source\_dir, 
which is the location of the {\file model} directory.  If you run from the 
top level directory: 
\command{ ./model/bin/w3\_setup model }

The setup can be modified by rerunning the {\file w3\_setup} program, or by 
manually editing the setup file. The `home' directory of \ws\ can only be 
changed by editing or removing the local {\file wwatch3.env}.

Note that previous versions of \ws\ required defining the 
An advanced option is to define the path of {\file wwatch3.env} in the 
user environment variable {\code WWATCH3\_ENV}. This is no longer needed. 
In addition, there is no longer an option of a global installation. 

The second set of setting up \ws\ is running the script 
{\file /model/bin/ww3\_from\_ftp.sh} to obtain binary or large 
files that are not stored in the git repository.  From the top directory: 
\command{./model/bin/ww3\_from\_ftp.sh} 
There are three prompts requiring user input in this script.  The first asks 
for the path the the top level directory, the second asks if you want to delete
the tar file that is copied (likely the answer is n for no) and the last asks 
to keep a folder that is used by this script (likely the answer is n for no).  

\vssub
\subsection{~Directory Structure}
\vssub

After cloning the \ws\ repository, the following directories are found on the 
top level. 

\begin{dlist}
\dit{manual   }{Manual directory.}
\dit{model    }{Model source code, build scritps, etc.}
\dit{regtests }{\ws\ executables.}
\dit{guide    }{Guide for \ws\ .}
\dit{smc\_docs }{Documentation and files for SMC grids.}
\end{dlist}

\noindent The following directories exist in the `model' directory of \ws.
 
\begin{dlist}
\dit{aux }{Raw auxiliary programs (source codes etc.).}
\dit{bin }{Executables and shell scripts for compiling and linking.}
\dit{ftn }{Source code and makefile.}
\dit{inp }{Input files.}
\dit{nml }{Namelist input files.}
\end{dlist}

\noindent The following directories are generated in the `model' directory 
after compiling the code. 

\begin{dlist}
\dit{exe }{\ws\ executables.}
\dit{mod }{Module files.}
\dit{obj }{Object files.}
\end{dlist}

\noindent

The  {\dir aux} directory has various additional tools, see the actual directory
for its contents. These include contributed {\it Matlab} codes, 
{\it IDL} tools, {\it bash} scripts and {\it GrADS} and {\it FORTRAN} programs.

Setting up \ws\ runs the installation the auxiliary programs will first process 
{\it FORTRAN} codes,
using the compiler as defined in the setup file {\file wwatch3.env}. 
Note that these codes are still in fixed format {\fortran-77}. The 
executables are stored in the directory {\dir bin}. A more detailed
description of these programs (including instructions on running the
executables) can be found in the documentation included in the above source
code files. After the compilation of these programs, several \unix\ shell
scripts and auxiliary files are installed in the {\dir bin} directory.

\begin{flist}
\fit{w3adc.f }{\ws\ {\fortran} preprocessor.}
\fit{w3prnt.f}{Print files (source codes) including page and line numbers.}
\fit{w3list.f}{Generate a generic source code listing.}

\fit{w3split.f}{Generate spectral bulletin identifying individual wave fields
  within a spectrum from the spectral output of the point output
  post-processor (see \para\ref{sec:ww3outp}). This is a legacy code
  superseded by generating bulletins directly from {\file ww3\_outp}. It is
  retained here for historical reasons only.}

\end{flist}

The {\dir bin} directory has various \unix\ scripts to manage the \ws\ framework.
The use of these scripts is explained in \para\ref{sec:comp}.  Note that the
following scripts acquire setup information from the \ws\ environment setup file
defined by {\code WWATCH3\_ENV}. Either defined by {\file w3\_setenv} which
read the local {\file wwatch3.env} or by the user environment file.

\vspace{\baselineskip} \noindent
Main programs used :

\begin{flist}
\fit{install\_ww3\_tar }{Script to install \ws\ from tar files.}
\fit{w3\_setup        }{Script for creating/editing the \ws\ environment setup
                        file. The default setup file is 
			{\file {\dir bin}/.wwatch3.env}. switch and compiler
			are given in arguments. (see options)}
\fit{w3\_clean        }{Script to clean up \ws\ directories by removing files
	                generated during compilation or test runs. 
			3 levels of clean-up. (see options)}
\fit{w3\_make         }{Script to compile and link components of \ws\
                        using a makefile. A list of programs can be given 
			in arguments.}
\fit{w3\_automake      }{Script to automatically compile separately sequential and
	                distributed programs in MPI, OMP or HYB depending on
	                the switch file content. A list of programs can be given
                        in arguments.}
\fit{w3\_new          }{Script to touch all correct source code files
                        to account for changes in compiler switches in
                        combination with the makefile.} 
\fit{ww3\_gspl.sh     }{Script to automate use of {\file ww3\_gspl} program 
                        (see \para\ref{sub:ww3gspl}).}
\fit{arc\_wwatch3\_tar}{Program to archive versions of \ws\ in the 
                        directory {\dir arc}.}
\fit{ww3\_from\_ftp.sh  }{Script to download all the binary files not provided by git.}
\end{flist}

\noindent
Examples files provided : 

\begin{flist}
\fit{switch\_{\it xxx} }{Examples of preprocessor switches provided by users
	                or developers. (\para\ref{sec:switches})}
\end{flist}

\noindent               
Subprograms called :

\begin{flist}
\fit{w3\_setenv        }{Script to setup the environment based on 
	               {\file {\dir bin}/.wwatch3.env}.	Called by all 
		       auxiliary programs.}
\fit{comp.tmpl        }{Compiler script template {\file comp} used with
	               {\file cmplr.env}.}
\fit{link.tmpl        }{Link script template {\file link} used with
	               {\file cmplr.env}.}
\fit{cmplr.env        }{compiler options tested on intel, mpt, gnu, pgi with
                       optimized and debugging options. used with comp.tmpl
		       and link.tmpl}
\fit{make\_makefile.sh}{Script to generate the makefile based
                        on selections in the file {\file switch}}. 
\fit{ad3              }{Script to run the preprocessor {\file w3adc}
                        and the compile script {\file comp} for a given
                        source code file.}
\fit{ad3\_test        }{Test version of {\file ad3}, showing modifications
                        to original source file. This script does not
                        compile code.}
\fit{all\_switches    }{Generates a list of all {\code w3adc} switches 
                        present in the source code files.}
\fit{find\_switch     }{Script to find \ws\ source code files containing 
                       compiler switches (or arbitrary strings).}
\fit{sort\_switch     }{Order the switches present in the switch file.}
\fit{sort\_all\_switches}{Script to search all the switch files in \ws\
                	and call {\file sort\_switch}.}

\end{flist}


\noindent               
Extra programs :

\begin{flist}
\fit{comp.{\it xxx}   }{Compiler script {\file comp} for advanced setting.}
\fit{link.{\it xxx}   }{Link script {\file link} for advanced setting.}
\fit{make\_MPI        }{Script to separately compile MPI and non-MPI programs.
			(obsolete in future releases - use {\file w3\_automake})}
\fit{make\_OMP        }{Script to separately compile OpenMP and single threaded
			programs. (obsolete in future releases - use {\file w3\_automake})}
\fit{make\_HYB        }{Script to separately compile hybrid MPI-OpenMP and
			single threaded programs. (obsolete in future releases
			- use {\file w3\_automake})}
\fit{ln3              }{Script to make symbolic link of source code file
			to work directory. (not used)}
\fit{list             }{Script to print source code listing using 
			{\file w3prnt}. (not used)}
\fit{w3\_source       }{Script to generate a true \fortran\ source
			code for any of he \ws\ program elements. (not used)}
\fit{WW3\_switch\_process}{Perl script to process switch from a source file.
                	(not used)}
\end{flist}


After installation in the {\dir bin} directory, several GrADS scripts are
installed in the {\dir aux} directory.

\begin{flist}
\fit{cbarn.gs         }{Semi-standard GrADS script for displaying
                        color bars.}
\fit{colorset.gs      }{Script to define colors used in shading.}
\fit{profile.gs}      {Script to display profiling data generated by {\file
                       ww3\_multi}.} 
\fit{source.gs}       {Script for composite plot of spectra and source
                       terms (2-D polar or Cartesian plots in color or in
                       black and white).}
\fit{1source.gs}      {Script to plot single source term.}
\fit{spec.gs}         {Script to plot spectra.}
\fit{spec\_ids.gen}   {Data file used by spectral / source scripts.}
\end{flist}



\pb

